If it isn't just a shortcut to editing the equipment I'm not sure I like it being called equipItem. Especially with the potential dropping of another item. I want some more thoughts on naming. I like SulfurCube#swallow(ItemStack)

Alternatives I thought of:

• Engulf
• SwallowAndMaybeBarf
• Nom

Well its based in the nms method maybe just a tryEquipItem but the original name is fine to me... (maybe can mention the events for what this method can pass?)

I partially agree with mbax here, the method name should reflect that this is an attempt at equipping an item. I love cube.nom(ItemStack) /s. SulfurCube#attemptAbsorb / tryAbsorb / absorb would work. So would swallow. Its not really an active equipping.

Javadocs should mention that events are called.

Also unsure about the boolean return, how do I get the itemstack that was possibly dropped from the sulfur cube?

Tho the more I think about it the less convinced I am that this method is even needed in the first place. The use case for actually running the vanilla logic seem small. E.g. how often would a plugin really need to "simulate" a player actively attempting to place a block into a sulfur cube. Most of the times it'd probably be a direct set and playing the noise, which this method does not offer fine control over.
The primary motivation for adding this method seem to be related to API simplicity, which is a fair goal but that could be solved via a plain setter overload on the entity instead of exposing the vanilla method.

My thoughts for that being that this method has a lot of possibly unexpected side effects that are only exposed when reading the javadocs and that, from my perspective, most plugin developers will not be aiming for. Am a concerned that this addition will do more harm than good for a person just tab completing away SulfurCube, finding this method and then all of a sudden their items drop to the floor and a sound is playing when they were just trying to spawn in a sulfur cube with a block inside.

Introducing fine grained control over the individual actions the method does (sound playing, item dropping) would also balloon up the api surface and diff needed when most plugin developers can simply write out a single if hasBlockSwallowed() dropBlockSwallowed() before their setter if they want to do so.

Your concerns sound very reasonable. Based on that, would the following changes be accepted?

• Addition of SulfurCube#setEquipped(ItemStack), with the sole purpose of silently setting the currently equipped item stack, with the goal being API simplicity.
• Addition of ItemStack SulfurCube#getEquipped(), the appropriate getter, same use case as above.
• Rename boolean equipItem(ItemStack) to boolean swallow(ItemStack), noting the events + logical difference to setEquipped, cross referencing both in @see Javadoc note?

Yea I think that seems fine. The equip methods can be default in the interface and forward directly there to the correct but maybe hard to know about equipment methods using BODY slot. They should also probably explain that they are a simple alias / utility for that.